Fox's Git Mirrors
docs/profile-schema.md HEAD (ed7be254) Text, 6.87 KB
Profile Schema v1
This document defines the public Armory profile manifest contract. Profiles are meta-packages: they describe a curated environment by referencing other Armory artifacts instead of copying dependency payloads.
File layout
A profile lives at:
T282828
profiles/<slug>/
├── profile.toml
├── README.md
└── LOCK.json # optional
T383838<slug> is the public package ID and must match T383838profile.slug.
Manifest structure
T282828
[profile]
schema = "dev.styrene.omegon.profile.v1"
id = "dev.styrene.omegon.profile.python-shop"
slug = "python-shop"
name = "Python Shop"
version = "1.0.0"
description = "Curated Python engineering stack for code review, feature work, testing, packaging, and secure service development."
category = "engineering"
license = "MIT"
min_omegon = "0.21.0"
[defaults]
posture = "architect"
thinking_level = "medium"
max_turns = 50
persona = "systems-engineer"
tone = "concise"
[export]
default_format = "generic-markdown"
include_optional = false
include_native_notes = true
[[dependencies]]
kind = "persona"
id = "systems-engineer"
version = ">=1.0.0"
required = true
activate = "always"
scope = "global"
purpose = "Default systems-engineering persona."
portable = true
T383838[profile]
┌─────────────┬─────────────────────────────────┬──────────────────────────────────────────────────┐
│ Field │ Required │ Rule │
├─────────────┼─────────────────────────────────┼──────────────────────────────────────────────────┤
│ T383838schema │ recommended now, required later │ Must be T383838dev.styrene.omegon.profile.v1 when pres… │
│ T383838id │ yes │ Must be T383838dev.styrene.omegon.profile.<slug>. │
│ T383838slug │ yes │ Must match the directory name. │
│ T383838name │ yes │ Human label. │
│ T383838version │ yes │ Strict semver T383838MAJOR.MINOR.PATCH. │
│ T383838description │ yes │ Public description, max 220 chars. │
│ T383838category │ yes │ Controlled public category. │
│ T383838license │ yes │ SPDX-style license string. │
│ T383838min_omegon │ yes │ Minimum native Omegon version, T383838MAJOR.MINOR.PATC… │
└─────────────┴─────────────────────────────────┴──────────────────────────────────────────────────┘
Allowed categories for public Armory v1:
T282828
engineering
knowledge
operations
review
T383838[defaults]
Defaults describe native Omegon runtime posture. They are hints for degraded exports.
┌────────────────┬──────────┬─────────────────────────────────────────────────────────┐
│ Field │ Required │ Rule │
├────────────────┼──────────┼─────────────────────────────────────────────────────────┤
│ T383838posture │ yes │ T383838architect, T383838implementer, T383838reviewer, T383838operator, or T383838analyst. │
│ T383838thinking_level │ yes │ T383838low, T383838medium, T383838high, or T383838max. │
│ T383838max_turns │ yes │ Integer 1–200. │
│ T383838persona │ yes │ Must match a required T383838persona dependency. │
│ T383838tone │ yes │ Must match a required T383838tone dependency. │
└────────────────┴──────────┴─────────────────────────────────────────────────────────┘
T383838[export]
Export settings describe non-native degradation defaults. This section is optional for backward compatibility; when absent, exporters use conservative defaults.
┌──────────────────────┬──────────────────┬────────────────────────────────────────────────────────┐
│ Field │ Default │ Rule │
├──────────────────────┼──────────────────┼────────────────────────────────────────────────────────┤
│ T383838default_format │ T383838generic-markdown │ T383838generic-markdown, T383838agents-md, T383838claude-md, or T383838cursor-rul… │
│ T383838include_optional │ T383838false │ Whether optional portable dependencies are included b… │
│ T383838include_native_notes │ T383838true │ Whether native-only extension setup notes are rendere… │
└──────────────────────┴──────────────────┴────────────────────────────────────────────────────────┘
T383838[[dependencies]]
┌──────────┬─────────────┬───────────────────────────────────────────────────────────────────┐
│ Field │ Required │ Rule │
├──────────┼─────────────┼───────────────────────────────────────────────────────────────────┤
│ T383838kind │ yes │ T383838skill, T383838persona, T383838tone, T383838extension, T383838agent, or T383838profile. │
│ T383838id │ yes │ Armory package ID; no paths or URLs. │
│ T383838version │ yes │ Semver range or exact version. │
│ T383838required │ yes │ Required dependencies must resolve before native activation. │
│ T383838activate │ yes │ T383838always, T383838auto, or T383838manual. │
│ T383838scope │ recommended │ T383838global, T383838project, or T383838session. Defaults to T383838global. │
│ T383838purpose │ recommended │ Short public rationale for why the dependency exists. │
│ T383838portable │ recommended │ Whether degraded exporters may include the dependency as content. │
│ T383838source │ no │ Named Armory source for multi-index installs. │
└──────────┴─────────────┴───────────────────────────────────────────────────────────────────┘
Dependency portability defaults by kind:
┌───────────┬──────────────────┬─────────────────────────────────────────────────────────────────┐
│ Kind │ Default portable │ Degraded behavior │
├───────────┼──────────────────┼─────────────────────────────────────────────────────────────────┤
│ T383838skill │ true │ Include T383838SKILL.md as instructions. │
│ T383838persona │ true │ Include T383838PERSONA.md as role/system prompt. │
│ T383838tone │ true │ Include T383838TONE.md as style guidance. │
│ T383838profile │ true │ Resolve recursively if cycle-free. │
│ T383838agent │ false │ Include blueprint note only unless explicitly portable. │
│ T383838extension │ false │ Native setup note only unless a portable interface is declared. │
└───────────┴──────────────────┴─────────────────────────────────────────────────────────────────┘
Resolver invariants
A valid public profile must satisfy:
1. T383838profile.slug matches the directory name.
2. T383838profile.id matches T383838dev.styrene.omegon.profile.<slug>.
3. T383838defaults.persona is a required persona dependency.
4. T383838defaults.tone is a required tone dependency.
5. Dependencies are unique by T383838(kind, id).
6. Required dependency references resolve in the current public Armory registry.
7. Profile dependencies are acyclic.
8. Extension dependencies may be optional unless the runtime truly cannot operate without them.
9. Native-only dependencies are not silently included in degraded exports.
10. Public payload lint passes for T383838profile.toml, T383838README.md, and optional T383838LOCK.json.
Lock file shape
Official profile releases should eventually publish T383838LOCK.json for reproducibility:
T282828
{
"schema": "dev.styrene.omegon.profile.lock.v1",
"profile": "python-shop",
"resolvedAt": "2026-05-17T00:00:00Z",
"dependencies": [
{
"kind": "skill",
"id": "python",
"version": "1.0.0",
"ref": "ghcr.io/styrene-lab/omegon-armory/skills/python:1.0.0",
"digest": "sha256:..."
}
]
}
Profiles may remain floating during early public Armory development. Locked official releases are the target state before treating profiles as reproducible install units.
Exporter implementation
The repo-local exporter renders profile dependencies into degraded prompt/config formats:
T282828
python3 scripts/export-profile.py python-shop --format generic-markdown --out dist/exports/python-shop.md
python3 scripts/export-profile.py security-review --format agents-md --out dist/exports/AGENTS.md
python3 scripts/export-profile.py typescript-shop --format claude-md --out dist/exports/CLAUDE.md
python3 scripts/export-profile.py docs-vault --format cursor-rules --out dist/exports/.cursorrules
Rules:
• required portable dependencies are included by default;
• optional portable dependencies require T383838--include-optional unless the profile export config says otherwise;
• native extensions render as setup notes, not prompt content;
• exports include provenance and generated-file headers;
• profile dependency recursion, lockfile resolution, OCI registry resolution, and memory fact export are intentionally deferred.
Exporter implications
Exporters should:
• include required portable dependencies by default;
• include optional portable dependencies only when requested or when T383838export.include_optional = true;
• render native-only extensions as setup notes, not prompt instructions;
• include provenance for every included dependency;
• preserve profile defaults as metadata;
• fail on unresolved required dependencies.
Served by rngit 1.5.2 - Generated in 0.03s